Expressions/es

Resumen

Es una expresión matemática que usa la notación de los operadores, funciones y constantes predefinidas matemáticas estándar como se describe a continuación. Además, la expresión puede hacer referencia a otras propiedades de objetos, y también utilizar condicionales. Los números en una expresión pueden tener una unidad opcional adjunta.

Los números pueden usar ya sea una coma , o un punto decimal . para separar los dígitos enteros de los decimales. Cuando se usa el marcador decimal, debe ser seguido por al menos un dígito. Por lo tanto, las expresiones 1.+2. y 1,+2, son inválidas, pero 1.0+2.0 y 1,0+2,0 son válidas.

Los operadores y las funciones son conscientes de la unidad y requieren combinaciones válidas de unidades, si se suministran. Por ejemplo, 2mm+4mm es una expresión válida, mientras que 2mm+4 no lo es. Esto también se aplica a las referencias a propiedades de objetos que tienen unidades, como las propiedades de longitud. Por lo tanto, Pad001.Length + 1 es inválido ya que agrega un número puro a una propiedad con unidades de longitud, se requiere Pad001.Length + 1mm.

Algunos errores relacionados con las unidades pueden parecer poco intuitivos, ya que las expresiones se rechazan o producen resultados que no coinciden con las unidades de la propiedad que se establece. Aquí hay unos ejemplos:

1/2mm no se interpreta como medio milímetro sino como 1/(2mm), lo que da como resultado: 0.5 mm^-1.

sqrt(2)mm no es válido porque la llamada a la función no es un número. Esto debe ingresarse como sqrt(2) * 1mm.

Argumentos de la función

Múltiples argumentos a una función pueden estar separados por un punto y coma ; o una coma seguida por un espacio , . En el último caso, la coma se convierte a un punto y coma después de la entrada. Cuando se usa un punto y coma, no es necesario un espacio final.

Los argumentos pueden incluir referencias a las celdas en una hoja de cálculo. Una referencia de celda consiste en la letra mayúscula de fila de la celda seguida de su número de columna, por ejemplo A1. También se puede hacer referencia a una celda utilizando el alias de la celda, por ejemplo, Spreadsheet.MyPartWidth.

Referencia de objetos

Como ya se mostró arribam puede hacer referencia a un objeto por su Datos Name. Pero también puedes usar su Datos Label. En el caso de un Datos Label, debe estar encerrado en doble símbolos << y >>, como <<Label>>.

Puede referenciar cualquier propiedad de un objeto. Por ejemplo, para referenciar la altura de un Cilindro puede usar Cylinder.Height o <<Label_of_cylinder>>.Height.

Para más información de como referenciar objetos, vea Referencia a los datos CAD.

Inicio

Constantes soportadas

Las siguientes constantes están soportadas.

Inicio

Operadores soportados

Los siguientes operadores son soportados.

Inicio

Funciones soportadas

Funciones matemáticas generales

Las siguientes funciones matemáticas son soportadas:

Funciones trigonométricas

Las Funciones trigonométricas utilizan el grado sexagesimal como unidad predeterminada. Para radianes, agregue rad después del primer valor de una expresión. Entonces, por ejemplo, cos(45) es lo mismo que cos(pi rad / 4). Las expresiones en grados pueden usar deg o °, por ejemplo, 360deg - atan2(3; 4) o 360° - atan2(3; 4). Si una expresión no tiene unidades y debe convertirse a grados o radianes para garantizar la compatibilidad, multiplíquela por 1deg, 1° o 1rad como apropiado, por ejemplo, (360 - X) * 1deg; (360 - X) * 1°; (0,5 + pi / 2) * 1rad.

Funciones exponenciales y logarítmicas

Funciones de redondeo, truncamiento y resto.

Inicio

Funciones estadísticas/agregadas

Aggregate functions take one or more arguments.

Individual arguments to aggregate functions may consist of ranges of cells. A range of cells is expressed as two cell references separated by a colon :, for example average(B1:B8) or sum(A1:A4; B1:B4). The cell references may also use cell aliases, for example average(StartTemp:EndTemp).

Las siguientes funciones agregadas son soportadas:

Inicio

Manipulación de cadenas

Identificación de cadena

Las cadenas se identifican en las expresiones rodeándolas con comillas angulares dobles de apertura/cierre (al igual que las etiquetas).

En el siguiente ejemplo, "TEXTO" se reconoce como una cadena: <<TEXTO>>

Concatenación de cadenas

Las cadenas se pueden concatenar usando el signo '+'.

El siguiente ejemplo <<MI>> + <<TEXTO>> se concatenará con "MITEXTO".

Conversión de cadenas

Los valores numéricos se pueden convertir en cadenas con la función str:

str(Box.Length.Value)

Formato de cadena

El formato de cadena se admite utilizando el estilo (antiguo) % de Python.

Todos los especificadores % tal como se definen en la documentación de Python.

Como ejemplo, supongamos que tiene un cubo predeterminado de 10 mm de lado llamado 'Box' (nombramiento predeterminado de FreeCAD), la siguiente expresión <<Longitud del cubo: %s>> % Box.Length se expandirá a "Longitud del cubo: 10.0 mm"

Para más de un especificador % utilice la siguiente sintaxis: <<La longitud del cubo es %s y el ancho es %s>> % tuple(Box.Length; Box.Width). O use concatenación: <<La longitud del cubo es %s>> % Box.Length + << y el ancho es %s>> % Box.Width. Ambos se expandirán a "La longitud del cubo es de 10.0 mm y el ancho es de 10.0 mm".

Está disponible un archivo de muestra de FreeCAD que utiliza formato de cadena en el foro

Inicio

Funciones de creación de objetos

Los siguientes objetos se pueden crear en expresiones utilizando las siguientes funciones:

matrix(
  a11; a12; a13; a14;
  a21; a22; a23; a24;
  a31; a32; a33; a34;
  a41; a42; a43; a44
)

Inicio

Funciones vectoriales

Function / Operator	Description
v1 + v2	Add two vectors.
v1 - v2	Subtract two vectors.
v * s	Uniformly scale a vector by s.
vangle(v1; v2)	Angle between two vectors in degrees.
vcross(v1; v2)	Cross product of two vectors ${\displaystyle v_{1}\times v_{2}}$.
v1 * v2	Dot product of two vectors ${\displaystyle v_{1}\cdot v_{2}}$.
vdot(v1; v2)
vlinedist(v1; v2; v3)	Distance between vector v1 and a line through v2 in direction v3.
vlinesegdist(v1; v2; v3)	Distance between vector v1 and the closest point on a line segment from v2 to v3.
vlineproj(v1; v2; v3)	Project vector v1 on a line through v2 in direction v3.
vnormalize(v)	Normalize a vector to a unit vector.
vplanedist(v1)	Distance between vector v1 and a plane defined by a point v2 and a normal v3.
vplaneproj(v1)	Project vector v1 on a plane defined by a point v2 and a normal v3.
vscale(v; sx; sy; sz)	Non-uniformly scale a vector by sx in the X direction, sy in the Y direction, and sz in the Z direction.
vscalex(v; sx)
vscaley(v; sy)
vscalez(v; sz)

Inicio

Funciones matriciales

Rotation and Placement can each be represented by a Matrix. The following functions all take in a Matrix, Rotation, or Placement as their first parameter denoted in the table below by m. The type of the returned object is the same as the object supplied in the first argument except when using mtranslate on a Rotation, in which case a Placement will be returned.

Inicio

Expresiones condicionales

Conditional expressions are of the form condition ? resultTrue : resultFalse. The condition is defined as an expression that evaluates to either 0 (false) or non-zero (true).

Note that to use a boolean property as the condition this syntax must be used: VarSet.MyBool == 1 ? 10 mm : 15 mm.

The following relational operators are defined:

Inicio

Unidades

Las unidades se pueden utilizar directamente en expresiones. El analizador los conecta con el valor anterior. Entonces 2mm o 2 mm es válido mientras que mm no es válido porque no hay un valor anterior.

All values must have a unit. Therefore you must in general use a unit for values in spreadsheets.
In some cases it works even without a unit, for example if you have e.g. in spreadsheet cell B1 just the number 1.5 and refer to it for a pad height. This only works because the pad height predefines the unit mm that is used if no unit is given. It will nevertheless fail if you use for the pad height e.g. Sketch1.Constraints.Width - Spreadsheet.B1 because Sketch1.Constraints.Width has a unit and Spreadsheet.B1 has not.

Se pueden ingresar directamente unidades con exponentes. Entonces, por ejemplo, mm^3 se reconocerá como mm³ y m^3 se reconocerá como m³.

Si tienes una variable cuyo nombre es el de una unidad debes poner la variable entre << >> para evitar que sea reconocida como una unidad. Por ejemplo, si tiene la dimensión Sketch.Constraints.A, se reconocerá como la unidad amperio. Por lo tanto debes escribirlo en la expresión como Sketch.Constraints.<<A>>.

El analizador de expresiones reconoce las siguientes unidades:

Cantidad de sustancia

Ángulo

Corriente

Capacitancia electrica

Carga eléctrica

Conductividad eléctrica

Inductancia eléctrica

Potencial eléctrico

Resistencia electrica

Energía/trabajo

Fuerza

Longitud

Intensidad luminosa

Flujo magnético

Densidad de flujo magnético

Masa

Potencia

Presión

Temperatura

Tiempo

Volumen

Unidades imperiales especiales

Unidades no compatibles

The following commonly used units are not yet supported, for some an alternative is provided:

Inicio

Caracteres y nombres no válidos

The expression feature is very powerful but to achieve this power it has some limitations concerning some characters. To overcome this, FreeCAD offers to use labels and reference them instead of the object names. In labels you can use almost all special characters.

In cases where you cannot use a label, such as the name of a sketch's constraints, you must be aware what characters are not allowed.

Etiquetas

For labels there are no invalid characters, however some characters need to be escaped:

For example, the label Sketch\002 must be referenced as <<Sketch\\002>>.

Nombres

Names of objects like dimensions, sketches, etc. may not have the characters or character sequences listed below, otherwise the name is invalid:

For example, the following name is valid: <<Sketch>>.Constraints.T2üßµ@. While these are invalid names: <<Sketch>>.Constraints.test\result_2 (\r means "carriage return") or <<Sketch>>.Constraints.mol (mol is a unit).

Since shorter names (especially if they have only one or two characters) can easily result in invalid names, consider using longer names and/or establishing a suitable naming convention.

Cell aliases

See Spreadsheet SetAlias.

Inicio

Referencia a los datos CAD

It is possible to use data from the model itself in an expression. To reference a property use object_name.property or <<object_label>>.property, labels must be enclosed in << and >>. If you want to use labels they must be unique.

All next examples reference the object by its name, but in all cases the object label can also be used.

If the property is a compound of fields, the individual fields can be accessed as object_name.property.field.

Para referenciar una lista de objetos use object_label.list[list_index]. Si quiere por ejemplo referenciar una restricción de un croquis use Sketch.Constraints[16]. Si está en el mismo croquis puede omitir su nombre y solo usar Constraints[16].Note que el índice inicia en 0, por lo que la restricción 17 tiene que ser referenciada como Constraints[16]

To reference the object itself use the _self pseudo property: object_name._self.

The following table shows some more examples:

Cyclic dependencies

FreeCAD checks dependencies based on the relationship between document objects, not properties. This means that you cannot provide data to an object and query that same object for results. For example, even though there are no cyclic dependencies when the properties themselves are considered, you may not have an object which gets its dimensions from a spreadsheet and then display the volume of that object in the same spreadsheet. You have to use two spreadsheets, one to drive your model and the other for reporting.

As a workaround it is possible to display a cell range from the second spreadsheet in the first (or vice versa) by creating a cell binding with the Hide dependency of binding option.

Another way to workaround cyclic dependencies is to hide the reference by using the href or hiddenref function for individual expressions, for example: href(Box.Length).

Please note that both mentioned workarounds should be used with caution, and that they do not work if the properties that are reported depend on dimensions that are driven from the same spreadsheet.

Inicio

Variables globales de todo el documento

There is no concept of global variables in FreeCAD at the moment. Instead, arbitrary variables can be defined as cells in a spreadsheet using the Spreadsheet workbench, and then be given a name using the alias property for the cell (right-click on cell). Then they can be accessed from any expression just as any other object property.

Inicio

Enlace entre documentos

It is possible (with limitations) to define a Property of an object in your current document (".FCstd" file) by using an Expression to reference a Property of an object contained in a different document (".FCstd" file). For example, a cell in a spreadsheet or the DatosLength of a Part Cube, etc. in one document can be defined by an Expression that references the X Placement value or another Property of an object contained in a different document.

A document's name is used to reference it from other documents. When saving a document the first time, you choose a file name; this is usually different from the initial default "Unnamed1" (or its translated equivalent). To prevent links being lost when the master document is renamed upon saving, it is recommended that you first create the master document, create a spreadsheet inside it, and save it. Subsequently, you can still make changes to the file and its spreadsheet but you should not rename it.

Once the master document with the spreadsheet is created and saved (named), it is safe to create dependent documents. For example, assuming you name the master document master, the spreadsheet modelConstants, and give a cell an alias-name Length, you can then access the value as:

master#modelConstants.Length

Note that the master document must be loaded for the values in the master to be available to the dependent document.

Of course, it's up to you to load the corresponding documents later when you want to change anything.

Inicio

Problemas conocidos / tareas pendientes

• FreeCAD does not yet have a built-in expression manager where all expressions in a document are listed, and can be created, deleted, queried, etc. But an addon is available: fcxref expression manager.
• Open bugs/tickets for Expressions can be found on GitHub.

Inicio

Scripting

import FreeCAD as App

doc = App.ActiveDocument
box = doc.addObject("Part::Box", "Box")
cyl = doc.addObject("Part::Cylinder", "Cylinder")
cyl_name = cyl.Name

box.setExpression("Height", f"{cyl_name}.Height / 2")
box.setExpression("Length", f"{cyl_name}.Radius * 2")
box.setExpression("Width", "Length")

doc.recompute()

# Expressions are stored in the ExpressionEngine property:
for prop, exp in box.ExpressionEngine:
    val = getattr(box, prop)
    print(f"Property: '{prop}' -- Expression: '{exp}' -- Current value: {val}")

Inicio

Power user documentation

• FreeCAD scripting: Python, Introduction to Python, Python scripting tutorial, FreeCAD Scripting Basics

---

• Modules: Builtin modules, Units, Quantity
• Workbenches: Workbench creation, Gui Commands, Commands, Installing more workbenches
• Meshes and Parts: Mesh Scripting, Topological data scripting, Mesh to Part, PythonOCC

---

• Parametric objects: Scripted objects, Viewproviders (Custom icon in tree view)
• Scenegraph: Coin (Inventor) scenegraph, Pivy
• Graphical interface: Interface creation, Interface creation completely in Python (1, 2, 3, 4, 5), PySide, PySide examples beginner, intermediate, advanced
• Macros: Macros, How to install macros
• Embedding: Embedding FreeCAD, Embedding FreeCADGui

---

• Other: Expressions, Code snippets, Line drawing function, FreeCAD vector math library (deprecated)

---

• Hubs: User hub, Power users hub, Developer hub